home *** CD-ROM | disk | FTP | other *** search
/ PsL Monthly 1993 December / PSL Monthly Shareware CD-ROM (December 1993).iso / prgmming / win / pascal / aftrdrk.exe / AFTERDAR.DOC < prev    next >
Encoding:
Text File  |  1991-08-18  |  14.7 KB  |  400 lines
  1. AfterDark SDK
  2. Copyright (C) Richard R. Sands CIS 70274,103
  3. All rights reserved
  4.  
  5. Translated from the C SDK from Berkeley Systems
  6. Copyright (C) Berkeley Systems
  7. All rights reserved
  8.  
  9.  
  10. This program is Public Domain.  I only ask that if you successfully write a
  11. module, please send me a copy of the .AD file.
  12.  
  13. If you have any questions regarding this document or the writing After Dark
  14. modules themselves, please feel free to mail me.
  15.  
  16.  
  17. ------------------------------------------------------------------------------
  18. OVERVIEW
  19. --------
  20. This is a Software Development Kit for Pascal to support writing modules for 
  21. the After Dark Screen Savers.  It is object oriented so writing the modules 
  22. is easier than doing it in C, and maintanence of those modules is safer / 
  23. easier than with the C SDK.
  24.  
  25. This unit exports two primary items: the AD object called tAfterDark and
  26. a procedure called "module" that you must export in your program.  The 
  27. tAfterDark object handles all initialization,  messages, and control values 
  28. from the AD system.  As an object, it provides several virtual methods that 
  29. you may override depending on the complexity of your saver.  Each method 
  30. corresponds to a message that the main AD program sends to the applications 
  31. and are documented in the After Dark manual and the C code.  I tried to keep 
  32. the types, constants, and (some) variable names the same as in the C SDK so 
  33. the C docuementation could also double as the Pascal SDK doc.
  34.  
  35.  
  36. ------------------------------------------------------------------------------
  37. COMPILING AND SETUP
  38. -------------------
  39. The recommended directory structure is (APP should be your module name):
  40.  
  41.             C:\AFTERDRK\PASDK
  42.                 AfterDark.Pas - tAfterDark object
  43.                 AfterDark.Doc - documentation
  44.             C:\AFTERDRK\PASDK\YourApp
  45.                 App      pas  - Your Pascal Application Code
  46.                 App      dll  - Compiled DLL
  47.  
  48.                 mak      bat  - Batch File to create .AD module
  49.                 App      def  - You must change first line to your module
  50.                                 name
  51.                 App      rc   - Resource script - Never need to change
  52.                 res_ids  h    - Resource include file
  53.                 cstr     rsc  - ADRES Resource
  54.                 ctrl1    rsc  -  "      "
  55.                 ctrl2    rsc  -  "      "
  56.                 ctrl3    rsc  -  "      "
  57.                 ctrl4    rsc  -  "      "
  58.                 cwin     rsc  -  "      "
  59.                 mname    rsc  -  "      "
  60.                 App      res  - Compiled Resource
  61.                 mak2     bat  - Advanced MAKE batch file
  62.                 Apppas   res  - Additional Resource file
  63.  
  64.  
  65. The contents of MAK.BAT
  66. ------------------------
  67.    del APP.ad
  68.    REM add -V to see messages...
  69.    rc APP.rc APP.dll
  70.    copy APP.dll c:\afterdrk\APP.ad
  71.  
  72.  
  73. The contents of APP.DEF (First lines changes only)
  74. --------------------------------------------------
  75.    LIBRARY        APP
  76.    DESCRIPTION    'Graphics Module Library'
  77.    EXETYPE        WINDOWS
  78.    STUB           'WINSTUB.EXE'
  79.    CODE           MOVEABLE
  80.    DATA           MOVEABLE SINGLE
  81.    HEAPSIZE       1024
  82.    EXPORTS        Module              @1
  83.    WEP            @2 RESIDENTNAME
  84.  
  85.  
  86. Normal module creation steps
  87. ----------------------------
  88.    1. Make a directory under PASDK and copy the files listed above into it.
  89.  
  90.    2. Write your library in Pascal
  91.       There is no need for the $R directive since you need to run MAK.BAT
  92.       anyway.  However, you do need $R if you are going to add your own
  93.       resources.  (See next part.)
  94.  
  95.    3. Edit the MAK.BAT file and APP.DEF file to contain the correct
  96.       application names.
  97.  
  98.    4. Write/Edit your resources with ADRES.EXE
  99.  
  100.    5. Compile the Pascal.
  101.  
  102.    6. Run the MAK batch file.
  103.       In my Program Manager group, in addition to having my APP as an icon,
  104.       I also have the batch file.  This way I can just double click the
  105.       batch file and proceed to the next step.
  106.  
  107.    7. Test your Module.
  108.       Press the control key and double click the After Dark icon to reload
  109.       all of the modules.
  110.  
  111.    8. Repeat steps 4 through 7 until a good module has hatched!
  112.  
  113.  
  114. Adding your own resources to the Resource file
  115. ----------------------------------------------
  116. Since RC.EXE destroys the existing resource file, you must create you
  117. resources in a second resource file.  Use WRT (or whatever) to create a new
  118. resource file.  Use ADRES.EXE to create the "standard" application resource
  119. file.  Compile your module as in the steps above to get RC.EXE to create a
  120. new APP.RES file.  Then use WRT to copy your resources into the APP.RES file.
  121. Now place a statement at the top of your module:  {$R APP.RES}.  Now rather
  122. than use MAK.BAT, use MAK2.BAT.  MAK2.BAT contains one line:
  123.  
  124.                   copy APP.dll c:\afterdrk\APP.ad
  125.  
  126. As long as you do not run RC.EXE you can modify your own resources as often
  127. as you like.  However, if you do modify the ADRES.EXE resources and run
  128. RC.EXE via MAK.BAT, you must recopy your special resources back into the
  129. APP.RES file via WRT.
  130.  
  131. This procedure sounds more complicated as it is because we are bootstrapping
  132. ourselves.  When actually done, it is as simple as using the normal method
  133. of building a AD application - if fact, it's faster.
  134.  
  135.  
  136. ------------------------------------------------------------------------------
  137. TAFTERDARK OBJECT
  138. -----------------
  139.  
  140. TYPE
  141.     PAfterDark = ^TAfterDark;
  142.     TAfterDark = object
  143.       DC: hDC;                { Provided Display Context }
  144.       lpSystemAD: pAdSystem;  { Pointer to AD System Param Block }
  145.       lpModule  : pAdModule;  { Pointer to Module's Parameters }
  146.       constructor Init;
  147.       destructor  Done; virtual;
  148.       function DoPreInitialize:Integer; virtual;
  149.       function DoInitialize:Integer;    virtual;
  150.       function DoBlank: Integer;        virtual;
  151.       function DoDrawFrame: Integer;    virtual;
  152.       function DoClose: Integer;        virtual;
  153.       function DoSelected: Integer;     virtual;
  154.       function DoAbout:Integer;         virtual;
  155.       function DoButtonMessage1(Value:Integer):Integer; virtual;
  156.       function DoButtonMessage2(Value:Integer):Integer; virtual;
  157.       function DoButtonMessage3(Value:Integer):Integer; virtual;
  158.       function DoButtonMessage4(Value:Integer):Integer; virtual;
  159.     end;
  160.  
  161. function Module(iMessage:Integer; hDrawDC:hDC; AdSystem:THandle):Integer;  EXPORT;
  162.  
  163.  
  164. ------------------------------------------------------------------------------
  165. Module
  166. ------
  167. Purpose    : The message dispatcher for After Dark.
  168.  
  169. Declaration:  
  170.              function Module(iMessage:Integer; hDrawDC:hDC;
  171.                              AdSystem:THandle):Integer;  EXPORT;
  172.  
  173. Comments   : This routine handles all messages from the After Dark program.
  174.              It will decipher the messages and call the correct tAfterDark
  175.              object method.  You must place the statement
  176.  
  177.                              EXPORTS Module;
  178.  
  179.              in your module so the DLL is correctly compiled.  Other than
  180.              that, you need to nothing.
  181.  
  182.  
  183. ------------------------------------------------------------------------------
  184. tAfterDark.Init
  185. ---------------
  186. Purpose    : Initializes the Pascal SDK Module
  187.  
  188. Declaration:  
  189.          constructor Init;
  190.  
  191. Override   : Rarely.  This should only be called once in the modules mainline
  192.          routine.
  193.  
  194. Comments   : All this routine does is "hook" in the module to After Dark.  
  195.          It should not do any other initialization (See the 
  196.          DoPreInitialize/DoInitialize methods)
  197.  
  198. See Also   : Done, DoPreInitialize, DoInitialize, DoClose
  199.  
  200.  
  201. ------------------------------------------------------------------------------
  202. tAfterDark.Done
  203. ---------------
  204. Purpose    : Called during the WEP routine.
  205.  
  206. Declaration:  
  207.          destructor Done; virtual;
  208.  
  209. Override   : Rarely.
  210.  
  211. Comments   : This is called by the Windows Exit Proc.  It is for any tasks
  212.              that need to be done when the module is unloaded.  Normally, you
  213.              do not need to perform any actions here.
  214.  
  215. See Also   : DoClose
  216.  
  217.  
  218. ------------------------------------------------------------------------------
  219. tAfterDark.DoPreInitialize
  220. --------------------------
  221. Purpose    : Called whenever the Windows is about to go to "sleep".
  222.  
  223. Declaration:  
  224.          function DoPreInitialize:Integer; virtual;
  225.  
  226. Override   : Often.
  227.  
  228. Comments   : This method should reset the value of any variables you need to
  229.              operate your module.  You should not allocate memory here, since
  230.              it is called many times without a corresponding "cleanup"
  231.              routine.
  232.  
  233. See Also   : DoInitialize
  234.  
  235.  
  236. ------------------------------------------------------------------------------
  237. tAfterDark.DoInitialize
  238. -----------------------
  239. Purpose    : Called when the module is loaded into memory.
  240.  
  241. Declaration:  
  242.          function DoInitialize:Integer; virtual;
  243.  
  244. Override   : Often.
  245.  
  246. Comments   : This method should allocate memory for your application, and set
  247.              the initial values of any variables your module requires.  This
  248.              will always have a matching DoClose called so you may deallocate
  249.              your memory here.
  250.  
  251. See Also   : DoClose
  252.  
  253.  
  254. ------------------------------------------------------------------------------
  255. tAfterDark.DoClose
  256. ------------------
  257. Purpose    : Cleanup Method.  Called when the module is unloaded from memory.
  258.  
  259. Declaration:  
  260.          function DoClose:Integer; virtual;
  261.  
  262. Override   : Often.
  263.  
  264. Comments   : This method should deallocate any memory your application had
  265.              allocated.  It is called once.  This is where you may write
  266.              your control values to the AD_PREFS.INI file.
  267.  
  268. See Also   : DoInitialize
  269.  
  270.  
  271. ------------------------------------------------------------------------------
  272. tAfterDark.DoBlank
  273. ------------------
  274. Purpose    : Called when After Dark requests a blank screen
  275.  
  276. Declaration:  
  277.          function DoBlank:Integer; virtual;
  278.  
  279. Override   : Once in awhile.
  280.  
  281. Comments   : This should blank the screen upon request from After Dark if
  282.              your module allows it.  If you override this method, you must
  283.              call it's ancestor tAfterDark.DoBlank since this method also
  284.              sets up your control values.
  285.  
  286.  
  287. ------------------------------------------------------------------------------
  288. tAfterDark.DoDrawFrame
  289. ----------------------
  290. Purpose    : Called repeatedly when Windows is "sleeping".
  291.  
  292. Declaration:  
  293.          function DoDrawFrame:Integer; virtual;
  294.  
  295. Override   : Always (for all practical purposes).
  296.  
  297. Comments   : This is the work-horse method.  It is responsible for actually
  298.              drawing the screen animation.  You should do as little work as
  299.              possible so windows remains "lively".
  300.  
  301.  
  302. ------------------------------------------------------------------------------
  303. tAfterDark.DoSelected
  304. ---------------------
  305. Purpose    : Called whenever your module is selected from the control panel.
  306.  
  307. Declaration:  
  308.          function DoSelected:Integer; virtual;
  309.  
  310. Override   : Once in awhile.
  311.  
  312. Comments   : This routine allows you to disable/enable your controls.
  313.  
  314.  
  315. ------------------------------------------------------------------------------
  316. tAfterDark.DoAbout
  317. ------------------
  318. Purpose    : Called when the "About" window in the Control Panel is
  319.              activated.
  320.  
  321. Declaration:  
  322.          function DoAbout:Integer; virtual;
  323.  
  324. Override   : Once in awhile.
  325.  
  326. Comments   : This allows you to animate (or whatever) you about screen.
  327.              Normally, After Dark will display your module information with
  328.              whatever you have placed via the ADRES.EXE program, however,
  329.              this allows you to perform more tasks.
  330.  
  331.  
  332. ------------------------------------------------------------------------------
  333. tAfterDark.DoButtonMessageX
  334. ---------------------------
  335. Purpose    : These are called whenever your module's controls are moved by
  336.              the user.
  337.  
  338. Declaration:  
  339.              function DoButtonMessage1(Value:Integer):Integer; virtual;
  340.              function DoButtonMessage2(Value:Integer):Integer; virtual;
  341.              function DoButtonMessage3(Value:Integer):Integer; virtual;
  342.              function DoButtonMessage4(Value:Integer):Integer; virtual;
  343.  
  344. Override   : Often.
  345.  
  346. Comments   : These routines will give you the value of the controls whenever
  347.              the user moves the controls via the control panel.
  348.  
  349. See also   : DoBlank
  350.  
  351.  
  352.          ----------------end-of-author's-documentation---------------
  353.  
  354.                          Software Library Information:
  355.  
  356.                     This disk copy provided as a service of
  357.  
  358.                            Public (software) Library
  359.  
  360.          We are not the authors of this program, nor are we associated
  361.          with the author in any way other than as a distributor of the
  362.          program in accordance with the author's terms of distribution.
  363.  
  364.          Please direct shareware payments and specific questions about
  365.          this program to the author of the program, whose name appears
  366.          elsewhere in  this documentation. If you have trouble getting
  367.          in touch with the author,  we will do whatever we can to help
  368.          you with your questions. All programs have been tested and do
  369.          run.  To report problems,  please use the form that is in the
  370.          file PROBLEM.DOC on many of our disks or in other written for-
  371.          mat with screen printouts, if possible.  PsL cannot debug pro-
  372.          programs over the telephone, though we can answer questions.
  373.  
  374.          Disks in the PsL are updated  monthly,  so if you did not get
  375.          this disk directly from the PsL, you should be aware that the
  376.          files in this set may no longer be the current versions. Also,
  377.          if you got this disk from another vendor and are having prob-
  378.          lems,  be aware that  some files may have become corrupted or
  379.          lost by that vendor. Get a current, working disk from PsL.
  380.  
  381.          For a copy of the latest monthly software library newsletter
  382.          and a list of the 3,000+ disks in the library, call or write
  383.  
  384.                            Public (software) Library
  385.                                P.O.Box 35705 - F
  386.                             Houston, TX 77235-5705
  387.  
  388.                                  Orders only:
  389.                                 1-800-2424-PSL
  390.                               MC/Visa/AmEx/Discover
  391.  
  392.                           Outside of U.S. or in Texas
  393.                           or for general information,
  394.                               Call 1-713-524-6394
  395.  
  396.                           PsL also has an outstanding
  397.                           catalog for the Macintosh.
  398.  
  399.  
  400.